用微信扫码二维码

分享至好友和朋友圈

关注程序员的故事，一起用技术改变世界

SpringFox介绍

SpringFox 是一个开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。 官方定义为： Automated JSON API documentation for API's built with Spring。

Swagger介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

SpringFox使用教程

第一步： Maven框架机构Springboot项目，依赖SpringFox包：

io.springfoxgroupId> springfox-boot-starterartifactId> 3.0.0version> dependency>

第二步： 在Springboot项目启动添加注解@EnableOpenApi:

package com.missye.swagger; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.oas.annotations.EnableOpenApi; @EnableOpenApi @SpringBootApplication public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class, args); } }

第三步 ：创建测试API接口，包含实体类/控制器

用户实体类：

package com.missye.swagger; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; /** * 用户实体类信息 * @author missye * @since 2020/07/21 */ @Data @NoArgsConstructor @AllArgsConstructor @ApiModel("用户基本信息") public class SysUser { /** * 用户名 */ @ApiModelProperty("用户名") private String userName; /** * 用户昵称 */ @ApiModelProperty("用户昵称") private String nickName; /** * 邮件 */ @ApiModelProperty("邮件") private String email; /** * 手机号 */ @ApiModelProperty("手机号") private String mobile; }

用户控制器：

package com.missye.swagger; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.List; /** * 用户控制器 * @author missye * @since 2020/07/21 */ @Api(tags = "用户管理控制器") @RestController @RequestMapping("/sysUser") public class SysUserController { /** * 保存用户信息 * @param sysUser * @return ResultT * @author missye * @since 2020/7/21 */ @ApiOperation("保存用户信息") @PostMapping("/saveSysUser") public ResultT saveSysUser(@RequestBody SysUser sysUser) { //保存用户信息 return ResultT.ok("用户保存成功！"); } /** * 获取用户信息 * @param sysUser * @return ResultT * @author missye * @since 2020/7/21 */ @ApiOperation("获取用户信息") @PostMapping("/getSysUser") public ResultT getSysUser(@RequestBody SysUser sysUser) { return ResultT.ok(new SysUser()); } /** * 获取所有用户信息 * @param * @return ResultT> * @author missye * @since 2020/7/21 */ @ApiOperation("获取所有用户信息") @PostMapping("/getAllSysUser") public ResultT> getAllSysUser() { return ResultT.ok(new ArrayList()); } }

API统一响应工具类：

package com.missye.swagger; import lombok.Data; import java.io.Serializable; import java.util.List; /** * Api响应结果信息 * @author missye * @program springboot-company * @since 2020-05-16 09:42 **/ public class ResultT implements Serializable { private static final long serialVersionUID = 9142315231410107803L; /** * 成功状态 * @ignore */ private static final Integer SUCCESS = 0; /** * 成功状态 * @ignore */ private static final String MSG_SUCCESS = "业务处理成功"; /** * 失败状态码 * @ignore */ private static final Integer FAIL = -1; /** * 失败状态码 * @ignore */ private static final String MSG_FAIL = "业务处理失败"; /** * 业务错误码 */ private Integer code; /** * 描述 */ private String msg; /** * 结果集 */ private T content; /** * 业务处理成功，但无业务数据 */ public ResultT() { this(SUCCESS, MSG_SUCCESS, null); } /** * 业务处理成功，但有业务数据 * @param content 结果数据 */ public ResultT(T content) { this(SUCCESS, MSG_SUCCESS, content); } /** * 默认处理时自定义业务编码，没有业务数据 * @param code 错误编码 * @param msg 提示消息 */ public ResultT(int code, String msg) { this(code, msg, null); } /** * 默认处理时，自定义业务编码消息和业务数据 * @param code 错误编码 * @param msg 提示消息 */ public ResultT(int code, String msg, T content) { this.setCode(code); this.setMsg(msg); this.setContent(content); } /** * 自定义返回错误的消息，无业务数据 * @param code 错误编码 * @param msg 错误消息 * @return 错误结果 */ public static ResultT error(int code, String msg) { return new ResultT(code, msg, null); } /** * 返回默认错误. 有业务数据 * @param msg 错误消息(业务错误) * @return 错误结果 */ public static ResultT error(String msg) { return new ResultT(FAIL, msg, null); } /** * 返回默认错误，无业务数据 * @return 错误结果 */ public static ResultT error() { return error(FAIL, MSG_FAIL); } /** * 返回自定义成功的消息，无业务数据 * @param code 自定义成功编码 * @param msg 正确消息 * @return 正确结果 */ public static ResultT ok(Integer code, String msg) { return new ResultT(code, msg); } /** * 成功默认成功状态，有业务数据 * @param content 业务数据可以是List、Entity等数据 * @return 正确结果 */ public static ResultT ok(T content) { return new ResultT(content); } /** * 返回默认成功的状态信息，无业务数据 * @return 正确结果 */ public static ResultT ok() { return new ResultT(); } /** * 根据业务条件返回成功或失败的结果,必须保证成功和失败返回的类型是一致的 * @param checked 检查条件 * @param sucess 条件为true时成功返回的消息 * @param fail 条件为false的失败返回的消息 * @return 返回结果 */ public static ResultT on(boolean checked, String sucess, String fail) { return checked ? ResultT.ok(SUCCESS, sucess) : ResultT.error(FAIL, fail); } /** * 获取结果编码 * @return 结果编码 * @author zengxueqi */ public Integer getCode() { return code; } /** * 设置结果编码 * @param code 结果编码 * @return * @author missye */ public ResultT setCode(Integer code) { this.code = code; return this; } /** * 获取消息提示 * @return 消息提示 * @author missye */ public String getMsg() { return msg; } /** * 设置消息提示 * @param msg 消息提示 * @return 对象 * @author missye */ public ResultT setMsg(String msg) { this.msg = msg; return this; } /** * 获取业务数据 * @return 业务数据 * @author zengxueqi */ public T getContent() { return content; } /** * 设置业务数据 * @param content 业务数据 * @return 结果数据 * @author missye */ public ResultT setContent(T content) { this.content = content; return this; } }

第四步： 启动Springboot项目，访问Swagger页面：http://localhost:8080/swagger-ui/index.html

打开其中一个API接口文档，可以包含接口的请求与响应的详细信息，并且支持在线接口测试。

注解说明

本文测试案例总共用到4个SpringFox注解，如下：

@Api： 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源。

@ApiOperation： 用在方法上，说明方法的作用，每一个url资源的定义。

@ApiModel： 描述一个Model的信息。

@ApiModelProperty： 描述一个model的属性。

以上就是Springboot集成SpringFox生成Swagger接口文档的详细教程，虽然Swagger存在代码入侵性，但是在Api接口测试方面，它还是非常的不错，目前还多大公司使用改插件，可见其便捷性了。

特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。

Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.